Ant WebUI
Overview What is Ant WebUI Ant WebUI is a web interface for launching and scheduling Apache Ant tasks. Makes efficient use of Ajax to make things easier. Originally created by Lingway in order to monitor, start or restart services remotely without any administrator knowledge. Requirements Ant WebUI has been tested on an Apache Tomcat 5.5 application server but should work on any Java 5 based application server. Installation Deploying the web application First of all download the web application from the SourceForge project downloads. A release consists of a zip file containing the WAR file and the configuration file. Copy the antwebui.war file to your webapps directory. If your server is not configured to automatically deploy applications, restart your server. Please note that the application will not work until you have setup its configuration. Configuring the projet repository Ant WebUI is built so that configuration is separated from the application itself. This allows safer updates and makes the application logic cleaner. Therefore, if you do not setup the configuration of the application first, the application will not start. For a standard configuration, copy the configuration.jar file to the antwebui/WEB-INF/lib directory. However, it is safer to review the configuration file included in the configuration.jar file. For now, configuration is quite easy as it consists in two parameters : * the directory where Ant projects will be stored * the XML file describing tasks scheduling Editing the configuration file The configuration file consists, for now, of a single bootstrap.xml file included in the configuration.jar file. The simplest way of editing the file, if you are not aware of the JAR format, is to rename the file from .jar to .zip, as the formats are compatible. The boostrap.xml file conforms to the Spring application context XML configuration syntax. Open the file and adjust the settings to your needs, editing the projectDirectory and scheduleFile properties : Note that for the same reasons as we separate the configuration file from the application, it is not recommanded to set the projects directory and schedules file withing your web application directory (you would loose data). Before you proceed Understanding the logic Ant WebUI was primarily made to have a nice replacement for ssh logins, simple monitoring and so on. We wanted to have some way to launch commands remotely without having to login. We found that using Apache Ant as a scripting language was nice as is it task based, and allows exactly what we want to do. Ant WebUI also includes the SSH Ant plugin. As Ant WebUI is still in early stages, you are currently limited on running tasks which are defined in a single XML project file, and do not depend on external resources (other resources than the project file itself). Security As you may understand, allowing someone to run arbitrary Ant tasks should, and must, be considered as a potential security hole. Once a user has access to the Ant WebUI interface, he may upload any Ant project file, and therefore run arbitrary commands on the application server. Having this in mind, you should either : * consider that you know what you are doing and heavily trust your security settings and firewall rules * consider running the application server as its own user and group We strongly suggest you to take the second solution. Running an application with its own user and group is always a good idea, as you strongly limit its rights over the system. By doing this, you must also be aware that you will seriously restrict the number of commands Ant WebUI will be able to launch. Advanced security Ant WebUI does not, as today, offer any security in terms of login, tasks execution, ... You must entirely rely on your application server configuration (realms for Tomcat) and system security (Tomcat runs as its own user). Therefore, if Tomcat runs as tomcat user, it will not be allowed to perform things like rm -Rf /. That's a point. But what if you really want to run a task as root, with Ant WebUI, without lowering security ? We see two solutions. Either : * add the tomcat user to the sudoers list : but doing this is just like granting full access to the system to Tomcat. If you want to do so, you could definitely run Tomcat as root... * use the sshexec Ant task instead of the standard exec command. Doing this, you will limit the commands you run as root explicitely. As you'll read later on, however, there are some drawbacks on using this method. So as you may understand, Ant WebUI is just as powerful as it could be dangerous. Having this in mind, you should read on, and find out how easy it is to use. Using the web interface Open your browser at the following address : http://localhost:8080/antwebui/ (replace localhost with your server address). If you configured Ant WebUI properly, should should see a welcome windows appear. Click on the ok button, and a menu bar will appear. In the menu, select the very first item (Tasks manager -> Ant manager), and you should see the following : This is the main view of the application. It allows you to : * upload a new project file * launch an uploaded project * launch an specific task of an uploaded project * schedule a task * schedule a project The following features are not yet implemented but scheduled for addition : * edit an existing project file * delete a project file Uploading a new project This is where you should start from. Uploading a project file consists of sending to the server a valid Ant project file. Please be aware that the current view will never show you any misspelled / problematic ant file, so be careful (you may consult the server log in order to have more information if upload fails). To upload a new project, just click on the "Add" button, then select your Ant file. The project will automatically be loaded.\\\\ Note that you must have properly configured the projects directory in order to have it work correctly (please check that the application server has read/write rights on this directory). If you want to edit an existing project, you'll have, after it beeing uploaded, to edit the project file directly into this directory.\\\\ Here's a sample Ant project file : The previous file defines 4 tasks : * The classical "Hello, World !" * ps, which outputs the result of the "ps" command (Linux) * the result of the tail command over the tomcat log * a command which should be run with the spawn attribute set to true (explanation follows) Executing commands on the host Executing a command on the host is made thanks to the exec Ant task. Due to the web environment limitations, you must be aware of what you do when calling such commands : * processes will be spawned by the user of the application server (root or tomcat, depending on your setup) * most important, if you do not set the spawn attribute to true, the web application will hang until the child process ends. This means that if you launch an application remotely using this command, you must use the spawn attribute, unless you wish your client to hang forever. Note that the process will not end up if you close your client, which, in some circumstances, may be hazardous. Executing a command as superuser in an unpriviledged environment Most likely, you'll come to a situation where you'll want to launch commands as a superuser while your web application server runs as its own user. We've previously said that it is not recommanded to add the application server to the sudoers list. Therefore, we recommand, where possible, using the sshexec command. The sshexec task does quite the same as the exec one, but makes uses of an SSH server. Therefore, if your host does not run a SSH server, this solution will not suit your needs. If so, you may proceed. Here's a sample sshexec task : This will help you, but there are some serious drawbacks: * you must provide a valid login / password couple in your Ant file (so be careful that the projects directory is not readable by everyone) * the sshexec command does not support the spawn attribute, so it must end up correctly. You may use the timeout attribute Scheduling a task Last but not least, you'll now learn how to schedule tasks. You may schedule tasks/projects : * at application startup : when scheduling a task at startup, the tasks will be started when Ant WebUI will be started. This allows replacing calls to /etc/init.d scripts (in Linux) or services (Linux/Windows). * at fixed rates/dates/... : Ant WebUI makes use of the Quartz scheduling framework, which allows you to enter crontab-like expressions in order to schedule tasks. If you choose to schedule a task, you'll need to look at the Cron Triggers Quartz cron expression syntax Tutorial in order to be able to schedule tasks properly. Feature requests * deleting an existing project * editing an existing project directly * package project so that it can be bundled with its own additional classes, jars, configuration files, ... Category:Cloud GUI